fix(client)!: oauth.applications.delete resolves on the zero-byte 200 its route answers, instead of rejecting on every successful delete - #15675

Fixes #15451

ObjectStackClient.oauth.applications.delete ended return res.json() on a route that answers HTTP 200 with a zero-byte body, so it rejected with SyntaxError: Unexpected end of JSON input on every successful delete — after the row had already been committed away server-side. The method had no success path a caller could observe, and the obvious recovery (retry) failed differently, with the route's 404 not_found.

The fifth and last method of the oauth.* family, and the one #14312 / PR #15445 deliberately could not close: that ruling fenced the card to narrowing published return types, and no declared return type can be true while the res.json() call stands.

Re-driven, not inherited

The card's premise was re-measured on this branch rather than taken from the card. Real betterAuth + real @better-auth/oauth-provider over the real ObjectQL adapter on real SQLite, a real signed-up user and a real session, driven through the real ObjectStackClient with only the socket stood in for (@objectstack/verify's in-process app), against the showcase stack:

REPRO register      -> client_id + client_secret          (positive control)
REPRO get           -> 200                                (positive control)
REPRO getPublic     -> 200, the 7-column projection       (positive control)

REPRO WIRE delete-client -> status 200 | bytes 0
                          | content-type "application/json"
                          | content-length null

BEFORE  REPRO CLIENT delete       -> REJECTED: SyntaxError | Unexpected end of JSON input
        REPRO after-delete get    -> 404 {"error_description":"client not found","error":"not_found"}
        REPRO CLIENT delete RETRY -> REJECTED: Error | not_found

AFTER   REPRO CLIENT delete       -> RESOLVED | value = undefined
        REPRO after-delete get    -> 404 (unchanged — the row was always really gone)
        REPRO CLIENT delete RETRY -> REJECTED: Error | not_found (unchanged)

The three sibling methods answering normally on the same run are the harness's positive control: this is not a probe that failed to reach the route. The 404 after the client threw confirms the nastiest part of the card — the caller sees failure for a completed destructive operation, and the natural retry then produces a second, differently-shaped failure.

The harness was a throwaway; it is not in this diff. Everything it proved is pinned below at a level that does not need a stack boot.

The two open questions the card handed over, answered by measurement

1. What should the method resolve to? void. The route does distinguish "deleted" from "was already gone" — but on the error channel: a client that is not there answers 404 { error: 'not_found' }, which this.fetch already raises as a throw before any success value exists. The 200 answer carries zero bytes and therefore zero information, so a synthesised { deleted: true } would be a shape the wire never sends and strictly less informative than the 404 the caller already receives. The vendor agrees from its own side: StrictEndpoint('/oauth2/delete-client', ..., void).

2. How should the emptiness be detected? By reading the body. Both shortcuts were measured against the real route and both are unusable:

What it costs the day the route grows a payload: a non-empty body is still parsed, and its failure still thrown — so a malformed response stays loud and the only behaviour this change moves is the zero-byte case. A well-formed payload is validated and discarded under the declared void; surfacing it would be a deliberate, reviewable widening of the return type, never a silent change of shape. The parse is therefore load-bearing rather than dead code, and it is pinned as such.

What is in the diff

Both halves the triage comment asked for are here: the ledger entry goes in the same PR as the binding, and there is a pin that the method resolves on a zero-byte 200 — so restoring res.json() "for symmetry with its three siblings" cannot happen silently.

Its positive control is carried too: automation.trigger, bound by PR #13082, is absent from the ledger, so the zero I am reading is a real absence and not a mis-read of the file.

The BREAKING question, answered explicitly

BREAKING on two independent axes, and it makes a published method usable for the first time:

• type — the declared return moves off an erased any onto void. A read like (await ...delete(id)).deleted stops compiling (TS2339). ⚠️ Worth stating plainly: that code has never executed, because the promise never resolved. The compile break can only reach code that was already dead.
• runtime — a caller's catch stops firing on success. try { await ...delete(id) } catch {} still compiles and still runs, but its catch block was executing on every successful delete and now executes only on a real failure. Any workaround inside it is now inert.

Dropping the **BREAKING** token is not an available exit: ADR-0087's 2026-08-30 addendum closes it for this class in as many words.

⚠️ One gate is RED on purpose, and it needs a maintainer decision

check:adr-0087-registration reds on this changeset. That is deliberate and it is the only red. Both legs were measured, not guessed:

Leg 1 — the accurate category is unspellable. not-required (type-surface-only ...) is refused at predicate 4:

`type-surface-only packages/client/src/index.ts#delete` [predicate 4: narrowed-from-erased]
is false at HEAD: `delete`, which carries NO return annotation is still UNANNOTATED.

A reference is a bare identifier resolved to the first same-named definition, and this file declares ten members named delete. The first (line 2397) is unannotated at both revs, so the gate reports a true sentence about a member this diff never touched. parseSymbolRef requires a bare identifier, so the natural disambiguator with dots is rejected before any reading happens. That is #15627, filed off PR #15445 where the same ambiguity cost the get member its place in the marker — here it blocks the only member there is. Measurement added to that card.

Leg 2 — the one category that IS accepted is not claimed, deliberately. not-required (no-migration-prescription) passes mechanically: the prescription detector finds nothing in this body. It is not taken, because ADR-0087's own D7 records that PR #8277 held exactly this exemption on a detector miss rather than a positive finding, and names that as the pattern the sixth category was created to stop. Taking it here, with the measurement in hand, would repeat it knowingly.

⇒ Three exits, each closed by something already written down. A loud red with the reasoning recorded beats a green held by a category that does not describe the diff. The changeset carries a clearly-labelled non-claim note saying so, so the question is answered in writing even though the marker is absent — which is what the gate's own header says it exists to require.

The taxonomy half is filed as #15674; the mechanical half is #15627; the neighbouring open shape is #14502. Any of them is a docs/adr/** edit — governed, maintainer's by hand. This PR touches no governed surface (packages/client/** and .changeset/ only).

Verification — all at 3fd460ee402

pnpm --filter @objectstack/client test          34 files / 444 tests passed
pnpm --filter @objectstack/client typecheck     exit 0  (tsc --noEmit + check:test-typecheck)
pnpm --filter @objectstack/client check:exported-any-returns
        317 callables reached, 35 ledgered sites still open   exit 0
pnpm lint      (eslint . --no-inline-config, WHOLE repo, not narrowed)   exit 0

Derived gate union — node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, re-derived from a tree at origin/main after the first run raised its STALE TREE banner (5 commits behind). Change set: exactly the 5 paths above. 19 of 21 green on the first pass, and the two non-zero results were both NOT MEASURED rather than red, so both were converted into real measurements:

• check:dual-build-cjs-loads exit 3 — PREREQUISITE NOT MET ... nothing was measured. Built the 7 named packages, re-ran: exit 0, 103 require entry points across 66 packages load.
• check:changeset-no-major exit 254 — ERR_PNPM ... script not found; my invocation was wrong, not the gate. Ran node scripts/check-changeset-no-major.mjs: exit 0.

Every exit code above was captured after redirection to a file, never through a pipe.

Both test files were proven to be inside the tsc program with tsc -p tsconfig.test.json --listFiles before any claim was made about them — one hit each.

Ablation

Direction predicted in writing first: reverting index.ts alone, with the guards kept, should turn 4 of the 7 runtime pins red, break typecheck, and turn the ledger gate red in the unlisted direction. Observed, all three:

mutation on disk   removed-text (fixed signature) 0 · removed-text (marker) 0
                   injected-text (pre-fix res.json) 1 · blob differs from HEAD
mutation in dist   ablation-dist-preflight --absent -> marker absent from all 6 built files
PIN SUITE          exit 1 — Tests 4 failed | 3 passed (7)
TYPECHECK          exit 1 — 4 type errors in return-type-precision.test.ts
                   (the void equality, plus three now-unused ts-expect-error, TS2578)
LEDGER GATE        exit 1 — "ObjectStackClient.oauth.applications.delete resolves to
                   Promise of any and is not ledgered"

The three pins that stayed green are the ones that were green in both states and are labelled as such in the file: the malformed body, the whitespace-only body, and the 404. Restore was under an EXIT INT TERM trap using absolute paths, then proven three ways — blob-hash equality with the HEAD blob, an empty git diff HEAD, and an empty whole-tree git status --porcelain — and dist was rebuilt afterwards and re-checked for the marker, because the restore leg only restores source.

Sequencing

packages/client/src/index.ts is the #12104 family's measured hard serial. It was held by nobody at the ref this branch was cut from, and nothing that landed on origin/main in the meantime touched it (re-checked at merge). Cards #15447 and #12104 queue behind this file.

🤖 Generated with Claude Code

https://claude.ai/code/session_01D47qPfEWVPmhguWgBZCi5N

Generated by Claude Code